ugp.org.SerialX

Class Serializer

java.lang.Object

ugp.org.SerialX.Serializer

public class Serializer
extends java.lang.Object

Serializer is powerful utility class that allows you to serialize any object in Java using universal protocol system. This system is generating code similar to JSON called SerialX but unlike JSON, SerialX is based on determinate order of arguments. Also works with regular Java Base64 serialization. Note: Since 1.1.5 this is an new, improved and more powerful JSON!

Since:

1.0.0

Author:

PETO

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Serializer.NULL This is a "dummy" class that Serializer uses internally as an OOP programmatic interpretation of null.
static class	Serializer.ProtocolRegistry ProtocolRegistry, place to register protocols!

Field Summary

Fields

Modifier and Type	Field and Description
static java.text.DecimalFormat	decimalFormatter Decimal formatter to format decimal numbers (double, float) with during serialization!
static boolean	generateComments Set this on true and program will generate comments and report!
static java.util.Map<java.lang.String,java.lang.Object>	globalVariables Map with global variables, accessible for any serialized content (key is variable name, value is vale).
static Serializer.ProtocolRegistry	PROTOCOL_REGISTRY This is serialization protocol registry.
static boolean	serializeStringNormally Set this on true and String will be serialized normally, for instance "Hello world!"
static boolean	useProtocolIfCan Set this on true to force program to use SerializationProtocol also on java.io.Serializable objects.
static java.lang.Object	VOID This object is not going to be loaded!

Method Summary

Modifier and Type	Method and Description
static <T> T	Clone(T obj)
static java.lang.String	Code(java.lang.String code)
static java.lang.String	Comment(java.lang.String comment)
static <T> T	Instantiate(java.lang.Class<T> cls)
static java.lang.Object	InvokeStaticFunc(java.lang.Class<?> cls, java.lang.String name, java.lang.Object... args)
static java.lang.String	LoadFileToString(java.io.File f)
static java.lang.String	LoadFileToString(java.io.File f, int endlMode)
static Scope	LoadFrom(java.io.File file)
static <T> T	LoadFrom(java.io.File file, int index)
static <T> T	LoadFrom(java.io.File file, java.lang.String varName)
static Scope	LoadFrom(java.lang.CharSequence str)
static <T> T	LoadFrom(java.lang.CharSequence str, int index)
static <T> T	LoadFrom(java.lang.CharSequence str, java.lang.String varName)
static Scope	LoadFrom(java.io.Reader reader)
static <T> T	LoadFrom(java.io.Reader reader, int index)
static <T> T	LoadFrom(java.io.Reader reader, java.lang.String varName)
static Scope	LoadFromString(java.lang.String str) Deprecated.
static java.lang.String	SerializeClassic(java.io.Serializable obj)
static <A extends java.lang.Appendable> A	SerializeTo(A source, java.util.Map<java.lang.String,java.lang.Object> variables, java.lang.Object... objs)
static <A extends java.lang.Appendable> A	SerializeTo(A source, java.lang.Object... objs)
static <A extends java.lang.Appendable> A	SerializeTo(A source, Scope scope)
static void	SerializeTo(boolean append, java.io.File f, java.util.Map<java.lang.String,java.lang.Object> variables, java.lang.Object... objs)
static void	SerializeTo(boolean append, java.io.File f, java.lang.Object... objs)
static void	SerializeTo(java.io.File f, java.util.Map<java.lang.String,java.lang.Object> variables, java.lang.Object... objs)
static void	SerializeTo(java.io.File f, java.lang.Object... objs)
static void	SerializeTo(java.io.File f, Scope scope)
static java.lang.String	SerializeToString(java.util.Map<java.lang.String,java.lang.Object> variables, java.lang.Object... objs)
static java.lang.String	SerializeToString(java.lang.Object... objs)
static java.lang.String	SerializeToString(Scope scope)
static java.lang.String	StaticMember(java.lang.Class<?> cls, java.lang.String staticMethodName, java.lang.Object... args)
static java.lang.Class<?>[]	ToClasses(java.lang.Object... objs)
static java.lang.Object	UnserializeClassis(java.lang.String objStr)
static <T> java.lang.String	Var(java.lang.String name, T value)
static <T> java.lang.String	Var(java.lang.String name, T value, boolean isValue)

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

PROTOCOL_REGISTRY

public static final Serializer.ProtocolRegistry PROTOCOL_REGISTRY

This is serialization protocol registry. Do not add there two protocols applicable for exactly same classes! Also I recommend to register protocols in generic order of object that are they applicable for! In other words If some object Foo has child classes, protocol of these classes should be registered after each other. Defaultly there are protocols for serializing Collection, Map and CharSequence!

Since:

1.0.0

useProtocolIfCan

public static boolean useProtocolIfCan

Set this on true to force program to use SerializationProtocol also on java.io.Serializable objects. Doing this also might take less memory space then using classic java.io.Serializable. In some cases, java Serialization can be more effective than protocols sometimes not! You should try which gives you the best result, then you can also deactivate certain protocols that are less effective than Java serialization. For example for long strings, classic Java serialization is better than protocol, it will take less memory storage space, but performance is almost always far slower!
Note: Whole concept of SerialX is about avoiding classic Java serialization from many reasons so you most likely want this on true! Also protocol will be almost certainly faster classic serialization!

Since:

1.0.0

generateComments

public static boolean generateComments

Set this on true and program will generate comments and report!
Note: Keep this on false to achieve the best performance!

Since:

1.0.5

serializeStringNormally

public static boolean serializeStringNormally

Set this on true and String will be serialized normally, for instance "Hello world!" and not using protocols or java Base64!
Setting this on false will also make Strings unreadable for normal people!

Since:

1.2.0

decimalFormatter

public static java.text.DecimalFormat decimalFormatter

Decimal formatter to format decimal numbers (double, float) with during serialization! Default DecimalFormat will round decimal numbers to 3 decimal places (format pattern #.###)! Set this on null and decimal numbers will not be formated! Do this when you need accuracy!

globalVariables

public static java.util.Map<java.lang.String,java.lang.Object> globalVariables

Map with global variables, accessible for any serialized content (key is variable name, value is vale).

Since:

1.1.5

VOID

public static final java.lang.Object VOID

This object is not going to be loaded! This is way how Serializer interprets void during unzerializtion.

Since:

1.2.2

Method Detail

Var

public static <T> java.lang.String Var(java.lang.String name,
                                       T value)

Parameters:

name - | Name of variable.

value - | Value of variable.

Returns:

Variable in SerialX form to serialize as [name] = [value].

Since:

1.1.5

Var

public static <T> java.lang.String Var(java.lang.String name,
                                       T value,
                                       boolean isValue)

Parameters:

name - | Name of variable.

value - | Value of variable.

isValue - | True if variables value supposed to by visible also during value loading.

Returns:

Variable in SerialX form to serialize as [name] = [value].

Since:

1.1.5

StaticMember

public static java.lang.String StaticMember(java.lang.Class<?> cls,
                                            java.lang.String staticMethodName,
                                            java.lang.Object... args)

Parameters:

cls - | Class to invoke static member on!

staticMethodName - | Name of static member!

args - | Arguments of method (use this only if you are invoking method no field)!

Returns:

Static member invocation in SerialX form to serialize as [class]::[method | field] [args]...

Note: This will not invoke member from class directly, it will be invoked during unserialization, also no checks are performed here so this will not notify you if member or class does not exist!

Since:

1.2.2

Comment

public static java.lang.String Comment(java.lang.String comment)

Parameters:

comment - | The comment...

Returns:

Comment in SerialX form.

Since:

1.1.5

Code

public static java.lang.String Code(java.lang.String code)

Parameters:

code - | Code to convert in to SerialX code form.

Returns:

"${" + code + "}"

Since:

1.1.5

SerializeTo

public static void SerializeTo(java.io.File f,
                               java.lang.Object... objs)

Parameters:

f - | File to write in. This must be a text file (recommended extension .srlx).

objs - | Objects to serialize using SerialX.

Since:

1.0.0

SerializeTo

public static void SerializeTo(boolean append,
                               java.io.File f,
                               java.lang.Object... objs)

Parameters:

append - | When true, the new objects will be appended to files content (same objects will be also appended if there are some)!

f - | File to write in. This must be a text file (recommended extension .srlx).

objs - | Objects to serialize using SerialX.

Since:

1.1.0

SerializeTo

public static void SerializeTo(java.io.File f,
                               Scope scope)

Parameters:

f - | File to write in. This must be a text file (recommended extension .srlx).

scope - | Scope with variables and values to serialize!

Since:

1.2.0

SerializeTo

public static void SerializeTo(java.io.File f,
                               java.util.Map<java.lang.String,java.lang.Object> variables,
                               java.lang.Object... objs)

Parameters:

f - | File to write in. This must be a text file (recommended extension .srlx).

variables - | Map with variables to serialize. Keys are names of variables and values are values.

objs - | Objects to serialize using SerialX.

Since:

1.1.5

SerializeTo

public static void SerializeTo(boolean append,
                               java.io.File f,
                               java.util.Map<java.lang.String,java.lang.Object> variables,
                               java.lang.Object... objs)

Parameters:

append - | When true, the new objects will be appended to files content (same objects will be also appended if there are some)!

f - | File to write in. This must be a text file (recommended extension .srlx).

variables - | Map with variables to serialize. Keys are names of variables and values are values.

objs - | Objects to serialize using SerialX.

Since:

1.1.5

SerializeToString

public static java.lang.String SerializeToString(java.lang.Object... objs)

Parameters:

objs - | Objects to serialize using SerialX.

Returns:

String with objects serialized in SerialX code.

Since:

1.0.0

SerializeToString

public static java.lang.String SerializeToString(Scope scope)

Parameters:

scope - | Scope with variables and values to serialize!

Returns:

String with variables and objects serialized in SerialX code.

Since:

1.2.0

SerializeToString

public static java.lang.String SerializeToString(java.util.Map<java.lang.String,java.lang.Object> variables,
                                                 java.lang.Object... objs)

Parameters:

variables - | Map with variables to serialize. Keys are names of variables and values are values.

objs - | Objects to serialize using SerialX.

Returns:

String with variables and objects serialized in SerialX code.

Since:

1.1.5

SerializeTo

public static <A extends java.lang.Appendable> A SerializeTo(A source,
                                                             java.lang.Object... objs)

Parameters:

source - | Source Appendable to serialize objects into!

objs - | Objects to serialize using SerialX.

Returns:

Source Appendable with objects serialized in SerialX code.

Since:

1.2.5

SerializeTo

public static <A extends java.lang.Appendable> A SerializeTo(A source,
                                                             Scope scope)

Parameters:

source - | Source Appendable to serialize variables and objects into!

scope - | Scope with variables and values to serialize!

Returns:

Source Appendable with variables and objects serialized in SerialX code.

Since:

1.2.5

SerializeTo

public static <A extends java.lang.Appendable> A SerializeTo(A source,
                                                             java.util.Map<java.lang.String,java.lang.Object> variables,
                                                             java.lang.Object... objs)

Parameters:

source - | Source Appendable to serialize variables and objects into!

variables - | Map with variables to serialize. Keys are names of variables and values are values.

objs - | Objects to serialize using SerialX.

Returns:

Source Appendable with variables and objects serialized in SerialX code.

Since:

1.2.5

SerializeClassic

public static java.lang.String SerializeClassic(java.io.Serializable obj)
                                         throws java.lang.Exception

Parameters:

obj - | Object to serialize using classic Java serialization. Note: Slash will be replaced by back slash and Base64 padding with dash due to prevent conflict with SerialX syntax!

Returns:

String with serialized object.

Throws:

java.lang.Exception - - if an I/O error occurs while writing stream header

Since:

1.0.0

See Also:

java.lang.Base64

LoadFileToString

public static java.lang.String LoadFileToString(java.io.File f)

Parameters:

f - | Source file.

Returns:

All lines from source file as string.

Since:

1.1.5

LoadFileToString

public static java.lang.String LoadFileToString(java.io.File f,
                                                int endlMode)

Parameters:

f - | Source file.

endlMode - | 0 = no line brakes, 1 = always line brakes, 2 = line break only when contains with "//"!
Note: You almost always want endlMode on 1. So thats why you should use LoadFileToString(File) which is doing this automatically!

Returns:

Content of file as string.

Since:

1.2.0

LoadFrom

public static Scope LoadFrom(java.io.File file)

Parameters:

file - | Text file with serialized objects in SerialX to load.

Returns:

Unserialized objects and variables in Scope or empty Scope if string is empty. You can use negative indexes to get objects from back of this array since 1.1.0 (-1 = last element)!

Since:

1.0.0

LoadFromString

@Deprecated
public static Scope LoadFromString(java.lang.String str)

Deprecated.

DEPRECATED: Use LoadFrom(CharSequence) instead!

Parameters:

str - | SerialX string with serialized objects.

Returns:

Unserialized objects and variables in Scope or empty Scope if string is empty. You can use negative indexes to get objects from back of this array since 1.1.0 (-1 = last element)!

Since:

1.0.0

LoadFrom

public static Scope LoadFrom(java.lang.CharSequence str)

Parameters:

str - | CharSequence with serialized objects in SerialX to load.

Returns:

Unserialized objects and variables in Scope or empty Scope if string is empty. You can use negative indexes to get objects from back of this array since 1.1.0 (-1 = last element)!

Since:

1.2.5

LoadFrom

public static Scope LoadFrom(java.io.Reader reader)

Parameters:

reader - | Any Reader with serialized objects in SerialX to load.

Returns:

Unserialized objects and variables in Scope or empty Scope if string is empty. You can use negative indexes to get objects from back of this array since 1.1.0 (-1 = last element)!

Since:

1.2.5

LoadFrom

public static <T> T LoadFrom(java.io.File file,
                             int index)

Parameters:

file - | File with SerialX content.

index - | Index of value to get from lowest Scope.

Returns:

Value with index in lowest Scope. Similar to Serializer.LoadFrom(file).get(index) however this function is specifically designed to load only that 1 value witch saves alto of performance! But target value can't be using any variables declared outside and also can't be variable invocation itself! Also there might be some problems with commented code! Also there can't be no variables in file!

Since:

1.2.5

LoadFrom

public static <T> T LoadFrom(java.lang.CharSequence str,
                             int index)

Parameters:

str - | Any CharSequence with SerialX content.

index - | Index of value to get from lowest Scope.

Returns:

Value with index in lowest Scope. Similar to Serializer.LoadFrom(str).get(index) however this function is specifically designed to load only that 1 value witch saves alto of performance! But target value can't be using any variables declared outside and also can't be variable invocation itself! Also there might be some problems with commented code!

Since:

1.2.5

LoadFrom

public static <T> T LoadFrom(java.io.Reader reader,
                             int index)

Parameters:

reader - | Any Reader with SerialX content.

index - | Index of value to get from lowest Scope.

Returns:

Value with index in lowest Scope. Similar to Serializer.LoadFrom(reader).get(index) however this function is specifically designed to load only that 1 value witch saves alto of performance! But target value can't be using any variables declared outside and also can't be variable invocation itself!

Since:

1.2.5

LoadFrom

public static <T> T LoadFrom(java.io.File file,
                             java.lang.String varName)

Parameters:

file - | File with SerialX content.

varName - | Name of variable to load!

Returns:

Value of variable with varName in lowest Scope. Similar to Serializer.LoadFrom(file).get(varName) however this function is specifically designed to load only that 1 variable witch saves alto of performance! But target variable can't be using any variables declared outside! Also there might be some problems with commented code!

Since:

1.2.5

LoadFrom

public static <T> T LoadFrom(java.lang.CharSequence str,
                             java.lang.String varName)

Parameters:

str - | Any CharSequence with SerialX content.

varName - | Name of variable to load!

Returns:

Value of variable with varName in lowest Scope. Similar to Serializer.LoadFrom(str).get(varName) however this function is specifically designed to load only that 1 variable witch saves alto of performance! But target variable can't be using any variables declared outside! Also there might be some problems with commented code!

Since:

1.2.5

LoadFrom

public static <T> T LoadFrom(java.io.Reader reader,
                             java.lang.String varName)

Parameters:

reader - | Any Reader with SerialX content.

varName - | Name of variable to load!

Returns:

Value of variable with varName in lowest Scope. Similar to Serializer.LoadFrom(reader).get(varName) however this function is specifically designed to load only that 1 variable witch saves alto of performance! But target variable can't be using any variables declared outside! Also there might be some problems with commented code!

Since:

1.2.5

UnserializeClassis

public static java.lang.Object UnserializeClassis(java.lang.String objStr)
                                           throws java.lang.Exception

Parameters:

objStr - | String to unserialize by classic Java serialization. Note: Backslashes will be replaced by regular slashes and dashes with Base64 padding due to compatibility with SerialX syntax.

Returns:

Unsrialized object.

Throws:

java.io.IOException - - if an I/O error occurs while reading stream header.

java.lang.ClassNotFoundException - - Class of a serialized object cannot be found.

java.lang.Exception

Since:

1.0.0

See Also:

Base64

InvokeStaticFunc

public static java.lang.Object InvokeStaticFunc(java.lang.Class<?> cls,
                                                java.lang.String name,
                                                java.lang.Object... args)
                                         throws java.lang.reflect.InvocationTargetException

Parameters:

cls - | Class to invoke method from.

name - | Name of public static method to be called.

args - | Arguments of method. Arguments should be certain if method is overloaded!

Returns:

The returned result of called method or VOID if return type of method is void. If something when wrong you will be notified and null will be returned.

Throws:

java.lang.reflect.InvocationTargetException - if called method throws and exception while calling!

Since:

1.2.2

Clone

public static <T> T Clone(T obj)

Parameters:

obj - | Object to clone.

Returns:

Cloned object using SerializationProtocol or the same object as inserted one if cloning is not possible, for instance when protocol was not found and object is not instance of Cloneable. This clone function will always prioritized the Protocol variation, regular cloning is used only when there is no protocol registered or exception occurs.
Note: If there are protocols to serialize inserted object and all its sub-objects and variables then this clone will be absolute deep copy, meaning that making any changes to this cloned object or to its variables will not affect original one in any way! But keep in mind that this clone is absolute hoverer, based on protocols used, it does not need to be an 100% copy!

Since:

1.2.2

Instantiate

public static <T> T Instantiate(java.lang.Class<T> cls)
                         throws java.lang.NoSuchMethodException,
                                java.lang.reflect.InvocationTargetException

Parameters:

cls - | Class to instantiate.

Returns:

New blank instance of required class created by calling shortest public constructor with default values!
Note: Do not use this when your class contains final fields!

Throws:

java.lang.NoSuchMethodException - if there is no public constructor!

java.lang.reflect.InvocationTargetException - if called constructor throws and exception!

Since:

1.2.2

ToClasses

public static java.lang.Class<?>[] ToClasses(java.lang.Object... objs)

Parameters:

objs - | Array of objects.

Returns:

Array of inserted objects class types. Wrapper types of primitive values will be converted to primitive types! For instance: Integer.class -> int.class

Since:

1.2.2